home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / p_man / cat2 / standard / attr_get.z / attr_get
Encoding:
Text File  |  2001-04-17  |  8.8 KB  |  199 lines
  1.  
  2.  
  3.  
  4. AAAATTTTTTTTRRRR____GGGGEEEETTTT((((2222))))                                                        AAAATTTTTTTTRRRR____GGGGEEEETTTT((((2222))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      attr_get, attr_getf - get the value of a user attribute of a filesystem
  10.      object
  11.  
  12. CCCC SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.      ####iiiinnnncccclllluuuuddddeeee <<<<ssssyyyyssss////aaaattttttttrrrriiiibbbbuuuutttteeeessss....hhhh>>>>
  14.  
  15.      iiiinnnntttt aaaattttttttrrrr____ggggeeeetttt ((((ccccoooonnnnsssstttt cccchhhhaaaarrrr ****ppppaaaatttthhhh,,,, ccccoooonnnnsssstttt cccchhhhaaaarrrr ****aaaattttttttrrrrnnnnaaaammmmeeee,,,,
  16.                    cccchhhhaaaarrrr ****aaaattttttttrrrrvvvvaaaalllluuuueeee,,,, iiiinnnntttt ****vvvvaaaalllluuuueeeelllleeeennnnggggtttthhhh,,,, iiiinnnntttt ffffllllaaaaggggssss))));;;;
  17.  
  18.      iiiinnnntttt aaaattttttttrrrr____ggggeeeettttffff ((((iiiinnnntttt ffffdddd,,,, ccccoooonnnnsssstttt cccchhhhaaaarrrr ****aaaattttttttrrrrnnnnaaaammmmeeee,,,,
  19.                     cccchhhhaaaarrrr ****aaaattttttttrrrrvvvvaaaalllluuuueeee,,,, iiiinnnntttt ****vvvvaaaalllluuuueeeelllleeeennnnggggtttthhhh,,,, iiiinnnntttt ffffllllaaaaggggssss))));;;;
  20.  
  21. OOOOVVVVEEEERRRRVVVVIIIIEEEEWWWW
  22.      The _a_t_t_r group of system calls implement the ability for a user to attach
  23.      name/value pairs to objects within the filesystem.
  24.  
  25.      They could be used to store meta-information about the file.  For example
  26.      "character-set=kanji" could tell a document browser to use the Kanji
  27.      character set when displaying that document and "thumbnail=..." could
  28.      provide a reduced resolution overview of a high resolution graphic image.
  29.  
  30.      The _n_a_m_e_s can be up to MAXNAMELEN bytes in length, terminated by the
  31.      first 0 byte.  The intent is that they be printable ASCII (or other
  32.      character set) names for the attribute.
  33.  
  34.      The _v_a_l_u_e_s can be up to ATTR_MAX_VALUELEN (currently 64KB) of arbitrary
  35.      binary data.
  36.  
  37.      Attributes can be attached to all types of inodes:  regular files,
  38.      directories, symbolic links, device nodes, etc.
  39.  
  40.      There are 2 disjoint attribute name spaces associated with every
  41.      filesystem object.  They are the rrrrooooooootttt and uuuusssseeeerrrr address spaces.  The rrrrooooooootttt
  42.      address space is accessible only to privileged users, and only then by
  43.      specifying a flag argument to the function call.  A privileged user can
  44.      be either the superuser in an IIIIRRRRIIIIXXXX environment, or a user with
  45.      CCCCAAAAPPPP____DDDDEEEEVVVVIIIICCCCEEEE____MMMMGGGGTTTT capability.  Other users will not see or be able to modify
  46.      attributes in the rrrrooooooootttt address space.  The uuuusssseeeerrrr address space is
  47.      protected by the normal file permissions mechanism, so the owner of the
  48.      file can decide who is able to see and/or modify the value of attributes
  49.      on any particular file.
  50.  
  51.      Attributes are currently fully supported only in the XFS and CXFS
  52.      filesystem types.  Other filesystem types may provide a partial
  53.      implementation.
  54.  
  55. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  56.      The _a_t_t_r__g_e_t and _a_t_t_r__g_e_t_f functions provide a way to retrieve the value
  57.      of an attribute.
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. AAAATTTTTTTTRRRR____GGGGEEEETTTT((((2222))))                                                        AAAATTTTTTTTRRRR____GGGGEEEETTTT((((2222))))
  71.  
  72.  
  73.  
  74.      _P_a_t_h points to a path name for a filesystem object, and _f_d refers to the
  75.      file descriptor associated with a file.  If the attribute _a_t_t_r_n_a_m_e
  76.      exists, the value associated with it will be copied into the _a_t_t_r_v_a_l_u_e
  77.      buffer.  The _v_a_l_u_e_l_e_n_g_t_h argument is an input/output argument that on the
  78.      call to _a_t_t_r__g_e_t should contain the maximum size of attribute value the
  79.      process is willing to accept.  On return, the _v_a_l_u_e_l_e_n_g_t_h will have been
  80.      modified to show the actual size of the attribute value returned.  The
  81.      _f_l_a_g_s argument can contain the following symbols bitwise OR'ed together:
  82.  
  83.      ATTR_ROOT
  84.           Look for _a_t_t_r_n_a_m_e in the rrrrooooooootttt address space, not in the uuuusssseeeerrrr address
  85.           space.  (limited to use by super-user only)
  86.  
  87.      ATTR_DONTFOLLOW
  88.           Do not follow symbolic links when resolving a _p_a_t_h on an _a_t_t_r__g_e_t
  89.           function call.  The default is to follow symbolic links.
  90.  
  91.      _a_t_t_r__g_e_t will fail if one or more of the following are true:
  92.  
  93.      [ENOATTR]        The attribute name given is not associated with the
  94.                       indicated filesystem object.
  95.  
  96.      [E2BIG]          The value of the given attribute is too large to fit
  97.                       into the buffer.  The integer that the _v_a_l_u_e_l_e_n_g_t_h
  98.                       argument points to has been modified to show the actual
  99.                       number of bytes that would be required to store the
  100.                       value of that attribute.
  101.  
  102.      [ENOENT]         The named file does not exist.
  103.  
  104.      [EPERM]          The effective user ID does not match the owner of the
  105.                       file and the effective user ID is not super-user.
  106.  
  107.      [ENOTDIR]        A component of the path prefix is not a directory.
  108.  
  109.      [EACCES]         Search permission is denied on a component of the path
  110.                       prefix.
  111.  
  112.      [EINVAL]         A bit was set in the _f_l_a_g argument that is not defined
  113.                       for this system call.
  114.  
  115.      [EFAULT]         _P_a_t_h, _a_t_t_r_n_a_m_e, _a_t_t_r_v_a_l_u_e, or _v_a_l_u_e_l_e_n_g_t_h points outside
  116.                       the allocated address space of the process.
  117.  
  118.      [ELOOP]          A path name lookup involved too many symbolic links.
  119.  
  120.      [ENAMETOOLONG]   The length of _p_a_t_h exceeds {_M_A_X_P_A_T_H_L_E_N}, or a pathname
  121.                       component is longer than {_M_A_X_N_A_M_E_L_E_N}.
  122.  
  123.      _a_t_t_r__g_e_t_f will fail if:
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. AAAATTTTTTTTRRRR____GGGGEEEETTTT((((2222))))                                                        AAAATTTTTTTTRRRR____GGGGEEEETTTT((((2222))))
  137.  
  138.  
  139.  
  140.      [ENOATTR]      The attribute name given is not associated with the
  141.                     indicated filesystem object.
  142.  
  143.      [E2BIG]        The value of the given attribute is too large to fit into
  144.                     the buffer.  The integer that the _v_a_l_u_e_l_e_n_g_t_h argument
  145.                     points to has been modified to show the actual number of
  146.                     bytes that would be required to store the value of that
  147.                     attribute.
  148.  
  149.      [EINVAL]       A bit was set in the _f_l_a_g argument that is not defined for
  150.                     this system call, or _f_d refers to a socket, not a file.
  151.  
  152.      [EFAULT]       _A_t_t_r_n_a_m_e, _a_t_t_r_v_a_l_u_e, or _v_a_l_u_e_l_e_n_g_t_h points outside the
  153.                     allocated address space of the process.
  154.  
  155.      [EBADF]        _F_d does not refer to a valid descriptor.
  156.  
  157. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  158.      attr(1),
  159.      attr_list(2), attr_listf(2)
  160.      attr_multi(2), attr_multif(2)
  161.      attr_remove(2), attr_removef(2),
  162.      attr_set(2), attr_setf(2),
  163.  
  164. DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
  165.      Upon successful completion, a value of 0 is returned.  Otherwise, a value
  166.      of -1 is returned and _e_r_r_n_o is set to indicate the error.
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.